Developer Documentation

QuickTime 4 API Documentation

Wired Movies and Sprites

| Previous | Chapter Contents | Chapter Top | Next |

Sprite Media Handler Functions

This section describes the sprite media handler functions available to your application.

SpriteMediaSetSpriteProperty

The SpriteMediaSetSpriteProperty function sets the specified property of a sprite.

pascal ComponentResult SpriteMediaSetSpriteProperty (
                     MediaHandler mh,
                     QTAtomID spriteID,
                     long propertyType,
                     void* propertyValue);
mh
Specifies the sprite media handler for this operation.

spriteID
Specifies the ID of the sprite to be modified.

propertyType
Specifies the property to be set.

propertyValue
Specifies the new value of the property.

DISCUSSION

You call this function to modify a property of a sprite. You set the propertyType parameter to the property you want to modify. You set the spriteID parameter to the ID of the sprite whose property you want to set.

The type of data you pass for the propertyValue parameter depends on the property type. The following table lists the sprite properties and the data types of the corresponding property values.

Sprite Property

Data Type
kSpritePropertyMatrix
 MatrixRecord *
kSpritePropertyVisible
 short
kSpritePropertyLayer
 short
kSpritePropertyGraphicsMode
 ModifierTrackGraphicsModeRecord *
kSpritePropertyImageIndex
 short

RESULT CODES

noErr
 0 No error
invalidSpritePropertyErr
 -2065 Specified sprite property does not exist
invalidSpriteIndexErr
 -2067 Sprite index is out of range

SpriteMediaGetSpriteProperty

The SpriteMediaGetSpriteProperty function retrieves the value of the specified sprite property.

pascal ComponentResult SpriteMediaGetSpriteProperty (
                     MediaHandler mh,
                     QTAtomID spriteID,
                     long propertyType,
                     void* propertyValue);
mh
Specifies the sprite media handler for this operation.

spriteID
Specifies the ID of the sprite for this operation.

propertyType
Specifies the property whose value should be retrieved.

propertyValue
On return, contains a pointer to the value of the property.

DISCUSSION

You call this function to retrieve a value of a sprite property. You set the propertyType parameter to the property you want to retrieve. You set the spriteID parameter to the ID of the sprite whose property you want to retrieve.

On return, the propertyValue parameter contains a pointer to the specified property's value; the data type of that value depends on the property. The following table lists the sprite properties and the data types of the corresponding property values.

Sprite Property

Data Type
kSpritePropertyMatrix
 MatrixRecord *
kSpritePropertyVisible
 short *
kSpritePropertyLayer
 short *
kSpritePropertyGraphicsMode
 ModifierTrackGraphicsModeRecord *
kSpritePropertyImageIndex
 short *

RESULT CODES

noErr
 0 No error
invalidSpritePropertyErr
 -2065 Specified sprite property does not exist
invalidSpriteIndexErr
 -2067 Sprite index is out of range

SpriteMediaHitTestAllSprites

The SpriteMediaHitTestAllSprites function determines whether any sprites are at a specified location.

pascal ComponentResult SpriteMediaHitTestAllSprites (
                     MediaHandler mh,
                     long flags,
                     Point loc,
                     QTAtomID *spriteHitID);
mh
Specifies the sprite media handler for this operation.

flags
Specifies flags to control the hit testing operation. The following flags are valid for use with SpriteMediaHitTestAllSprites and SpriteMediaHitTestOneSprite :

spriteHitTestBounds
The specified location must be within the sprite's bounding box.

spriteHitTestImage
If both this flag and spriteHitTestBounds are set, the specified location must be within the shape of the sprite's image.

spriteHitTestInvisibleSprites

Set this flag if you want invisible sprites to be hit tested along with the visible ones.

spriteHitTestLocInDisplayCoordinates

Set this flag if the hit testing point is in display coordinates instead of local sprite track coordinates.

spriteHitTestIsClick

Set this flag if you want the hit testing operation to pass a click on to the codec currently rendering the sprites image. For example, this can be used to make the Ripple codec ripple.

loc
Specifies a point in the coordinate system of the sprite track's movie to test for the existence of a sprite.

spriteHitID
Contains a pointer to a short integer. On return, this integer contains the ID of the frontmost sprite at the location specified by loc . If no sprite exists at the location, the function sets the value of this parameter to 0.

DISCUSSION

You call this function to determine whether any sprites exist at a specified location in the coordinate system of a sprite track's movie. You can pass flags to this function to control the hit testing operation more precisely. For example, you may want the hit test operation to detect a sprite whose bounding box contains the specified location.

SpriteMediaCountSprites

The SpriteMediaCountSprites function retrieves the number of sprites that currently exist in a sprite track.

pascal ComponentResult SpriteMediaCountSprites (
                     MediaHandler mh,
                     short* numSprites);
mh
Specifies the sprite media handler for this operation.

numSprites
Contains a pointer to a short integer. On return, this integer contains the number of sprites for the sprite media's current time.

DISCUSSION

This function determines the number of sprites that currently exist based on the key frame that is in effect.

SpriteMediaCountImages

The SpriteMediaCountImages function retrieves the number of images that currently exist in a sprite track.

pascal ComponentResult SpriteMediaCountImages (
                     MediaHandler mh,
                     short* numImages);
mh
Specifies the sprite media handler for this operation.

numImages
Contains a pointer to a short integer. On return, this integer contains the number of images for the sprite media's current time.

DISCUSSION

This function determines the number of images that currently exist based on the key frame that is in effect.

SpriteMediaGetIndImageDescription

The SpriteMediaGetIndImageDescription function retrieves an image description for the specified image in a sprite track.

pascal ComponentResult SpriteMediaGetIndImageDescription (
                     MediaHandler mh,
                     short imageIndex,
                     ImageDescriptionHandle imageDescription);
mh
Specifies the sprite media handler for this operation.

imageIndex
Specifies the index of the image whose image description should be retrieved.

imageDescription
Specifies an image description handle. On return, this handle contains the image description for the specified image.

DISCUSSION

You set the imageIndex parameter to the index of the image whose image description you want to retrieve. The index must be between one and the number of available images. You can determine how many images are available by calling SpriteMediaCountImages .

The handle specified by the imageDescription parameter must be unlocked; this function resizes the handle if necessary.

RESULT CODES

noErr
 0 No error
paramErr
 -50 Invalid parameter specified
invalidImageIndexErr
 -2068 Image index is out of range

Memory Manager errors, as documented in Mac OS For QuickTime Programmers.

SpriteMediaGetDisplayedSampleNumber

The SpriteMediaGetDisplayedSampleNumber function retrieves the number of the sample that is currently being displayed.

pascal ComponentResult SpriteMediaGetDisplayedSampleNumber (
                     MediaHandler mh,
                     long* sampleNum);
mh
Specifies the sprite media handler for this operation.

sampleNum
Contains a pointer to a long integer. On return, this integer contains the number of the sample that is currently being displayed.

DISCUSSION

You call this function when you need to retrieve the sample number of the sample that is being displayed.

SpriteMediaGetSpriteName

The SpriteMediaGetSpriteName function returns the name of the sprite with the specified ID from the currently displayed sample.

pascal ComponentResult SpriteMediaGetSpriteName(
                                          MediaHandler mh,
                                          QTAtomID spriteID,
                                          Str255 spriteName);
mh
Specifies the sprite media handler for this operation.

spriteID
Specifies the sprite ID of the sprite name.

spriteName
Returns a Pascal string with the name of the sprite or an empty string if the sprite is unnamed.

SpriteMediaGetImageName

The SpriteMediaGetImageName function returns the name of the image with the specified index from the current key frame sample.

pascal ComponentResult SpriteMediaGetImageName(
                                          MediaHandler mh,
                                          short imageIndex,
                                          Str255 imageName);
mh
Specifies the sprite media handler for this operation.

imageIndex
Specifies the index of the image whose image name should be retrieved.

imageName
Returns a Pascal string with the image name of the image or an empty string if the image is unnamed.

SpriteMediaHitTestOneSprite

The SpriteMediaHitTestOneSprite function performs a hit testing operation on the sprite specified by the spriteID.

pascal ComponentResult SpriteMediaHitTestOneSprite(
                                          MediaHandler mh,
                                          QTAtomID spriteID,
                                          long flags,
                                          Point loc,
                                          Boolean *wasHit);
mh
Specifies the sprite media handler for this operation.

spriteID
Specifies the sprite ID of the sprite name.

flags
Specifies the flags to control the hit testing operation.

loc
The location loc should be in local coordinates of the sprite track, unless the spriteHitTestLocInDisplayCoordinates flag is set.

wasHit
Contains a pointer to a Boolean. If the sprite is hit, wasHit is set to true ; otherwise, it is set to false . This routine allows you to hit test a sprite which is fully or partially covered by other sprites.

Sprite indexes range from 1 to the number of sprites in the key sample.

SpriteMediaSpriteIndexToID

The SpriteMediaSpriteIndexToID function returns the ID of the sprite specified by spriteIndex in spriteID.

pascal ComponentResult SpriteMediaSpriteIndexToID(
                                          MediaHandler mh,
                                          short spriteIndex,
                                          QTAtomID *spriteID);
mh
Specifies the sprite media handler for this operation.

spriteIndex
Specifies the index of the sprite for this operation.

spriteID
Contains a pointer to the sprite ID of the sprite index. If a sprite with the specified index does not exist, the error paramErr is returned.

SpriteMediaIDToIndex

The SpriteMediaSpriteIDToIndex function returns the sprite index of the sprite specified by the spriteID.

 

pascal ComponentResult SpriteMediaSpriteIDToIndex(
                                          MediaHandler mh,
                                          QTAtomID spriteID,
                                          short *spriteIndex);
mh
Specifies the sprite media handler for this operation.

spriteID
Specifies the sprite ID of the sprite index.

spriteIndex
Contains a pointer to a short integer. If a sprite with the specified ID does not exist, the error invalidSpriteIDErr is returned.

SpriteMediaGetIndImageProperty

The SpriteMediaGetIndImageProperty function returns a property value for the image specified by imageIndex .

pascal ComponentResult SpriteMediaGetIndImageProperty(
                                          MediaHandler mh,
                                          short imageIndex,
                                          long imagePropertyType,
                                          void *imagePropertyValue);
mh
Specifies the sprite media handler for this operation.

imageIndex
Specifies the index of the image.

imagePropertyType

Specifies an image property type whose value is returned in imagePropertyValue . The allowed property types are:

kSpriteImagePropertyRegistrationPoint
imagePropertyValue is a FixedPoint value.

kSpriteImagePropertyGroupID
imagePropertyValue is a long integer.

imagePropertyValue

A pointer is set to the value of the image property.

Sprites Functions Specific to Wired Sprites

SpriteDescription Structure

© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top | Next |